<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Internationalization: libxfce4util Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="libxfce4util Reference Manual">
<link rel="up" href="libxfce4util-fundamentals.html" title="Xfce Fundamentals">
<link rel="prev" href="libxfce4util-Version-Information.html" title="Version Information">
<link rel="next" href="libxfce4util-Software-Licenses.html" title="Software Licenses">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
                  <a href="#libxfce4util-Internationalisation.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="libxfce4util-fundamentals.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libxfce4util-Version-Information.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="libxfce4util-Software-Licenses.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="libxfce4util-Internationalisation"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="libxfce4util-Internationalisation.top_of_page"></a>Internationalization</span></h2>
<p>Internationalization — Internationalization and Localization Support Functions</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_proto_type">
<col class="functions_proto_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<span class="returnvalue">void</span>
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-textdomain" title="xfce_textdomain ()">xfce_textdomain</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-get-file-localized" title="xfce_get_file_localized ()">xfce_get_file_localized</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-get-file-localized-r" title="xfce_get_file_localized_r ()">xfce_get_file_localized_r</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-get-dir-localized" title="xfce_get_dir_localized ()">xfce_get_dir_localized</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-get-dir-localized-r" title="xfce_get_dir_localized_r ()">xfce_get_dir_localized_r</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">gchar</span> *
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-get-path-localized" title="xfce_get_path_localized ()">xfce_get_path_localized</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<span class="returnvalue">guint</span>
</td>
<td class="function_name">
<a class="link" href="libxfce4util-Internationalisation.html#xfce-locale-match" title="xfce_locale_match ()">xfce_locale_match</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.other"></a><h2>Types and Values</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="other_proto_type">
<col class="other_proto_name">
</colgroup>
<tbody>
<tr>
<td class="define_keyword">#define</td>
<td class="function_name"><a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-FULL-MATCH:CAPS" title="XFCE_LOCALE_FULL_MATCH">XFCE_LOCALE_FULL_MATCH</a></td>
</tr>
<tr>
<td class="define_keyword">#define</td>
<td class="function_name"><a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-NO-MATCH:CAPS" title="XFCE_LOCALE_NO_MATCH">XFCE_LOCALE_NO_MATCH</a></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.includes"></a><h2>Includes</h2>
<pre class="synopsis">#include &lt;libxfce4util/libxfce4util.h&gt;
</pre>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.description"></a><h2>Description</h2>
<p>Provides functions to aid application developers making their software
localizable. It extends the basic internationalization support provided
by GLib 2.4 (and newer).</p>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="xfce-textdomain"></a><h3>xfce_textdomain ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>
xfce_textdomain (<em class="parameter"><code>const <span class="type">gchar</span> *package</code></em>,
                 <em class="parameter"><code>const <span class="type">gchar</span> *localedir</code></em>,
                 <em class="parameter"><code>const <span class="type">gchar</span> *encoding</code></em>);</pre>
<p>Sets up the translations for <em class="parameter"><code>package</code></em>
.</p>
<div class="refsect3">
<a name="xfce-textdomain.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>package</p></td>
<td class="parameter_description"><p>the package name.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>localedir</p></td>
<td class="parameter_description"><p>the <em class="parameter"><code>package</code></em>
s locale directory.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>encoding</p></td>
<td class="parameter_description"><p>the encoding to use the <em class="parameter"><code>package</code></em>
s translations
or <code class="literal">NULL</code> to use "UTF-8".</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-get-file-localized"></a><h3>xfce_get_file_localized ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
xfce_get_file_localized (<em class="parameter"><code>const <span class="type">gchar</span> *filename</code></em>);</pre>
<p>Checks if theres a version of <em class="parameter"><code>filename</code></em>
 which is localized to the current
locale. This is done by appending the full locale name to <em class="parameter"><code>filename</code></em>
, separated
by a '.'. If theres no file of that name, it retries using the full locale
name without the encoding (if any), then without the qualifier (if any) and
at last the base locale is tried. If all of those fails, a copy of <em class="parameter"><code>filename</code></em>

is returned.</p>
<div class="refsect3">
<a name="xfce-get-file-localized.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description"><p>name of a file to look for a localized version.</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="xfce-get-file-localized.returns"></a><h4>Returns</h4>
<p> path of the localized file or copy of <em class="parameter"><code>filename</code></em>
if no such
file exists. Returned string should be freed using <code class="function">g_free()</code>.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-get-file-localized-r"></a><h3>xfce_get_file_localized_r ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
xfce_get_file_localized_r (<em class="parameter"><code><span class="type">gchar</span> *buffer</code></em>,
                           <em class="parameter"><code><span class="type">gsize</span> length</code></em>,
                           <em class="parameter"><code>const <span class="type">gchar</span> *filename</code></em>);</pre>
<p>Similar in functionality to <a class="link" href="libxfce4util-Internationalisation.html#xfce-get-file-localized" title="xfce_get_file_localized ()"><code class="function">xfce_get_file_localized()</code></a>, but stores the
result in <em class="parameter"><code>buffer</code></em>
 instead of allocating a new buffer.</p>
<div class="refsect3">
<a name="xfce-get-file-localized-r.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>buffer</p></td>
<td class="parameter_description"><p>destination buffer to store the localized filename to.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description"><p>size of <em class="parameter"><code>buffer</code></em>
in bytes.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description"><p>name of a file to look for a localized version.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="xfce-get-file-localized-r.returns"></a><h4>Returns</h4>
<p> pointer to <em class="parameter"><code>buffer</code></em>
or <code class="literal">NULL</code> on error.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-get-dir-localized"></a><h3>xfce_get_dir_localized ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
xfce_get_dir_localized (<em class="parameter"><code>const <span class="type">gchar</span> *directory</code></em>);</pre>
<p>Similar to <a class="link" href="libxfce4util-Internationalisation.html#xfce-get-file-localized" title="xfce_get_file_localized ()"><code class="function">xfce_get_file_localized()</code></a>, but works on directory instead of
a file.</p>
<div class="refsect3">
<a name="xfce-get-dir-localized.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>directory</p></td>
<td class="parameter_description"><p>directory name to check for a localized variant.</p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="xfce-get-dir-localized.returns"></a><h4>Returns</h4>
<p> path of the localized directory name or copy of <em class="parameter"><code>directory</code></em>
if
no such directory exists. Returned string should be freed using
<code class="function">g_free()</code>.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-get-dir-localized-r"></a><h3>xfce_get_dir_localized_r ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
xfce_get_dir_localized_r (<em class="parameter"><code><span class="type">gchar</span> *buffer</code></em>,
                          <em class="parameter"><code><span class="type">gsize</span> length</code></em>,
                          <em class="parameter"><code>const <span class="type">gchar</span> *directory</code></em>);</pre>
<p>Similar to <a class="link" href="libxfce4util-Internationalisation.html#xfce-get-file-localized-r" title="xfce_get_file_localized_r ()"><span class="type">xfce_get_file_localized_r</span></a>, but works on directory instead
of regular file.</p>
<div class="refsect3">
<a name="xfce-get-dir-localized-r.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>buffer</p></td>
<td class="parameter_description"><p>destination buffer to store the localized filename to.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description"><p>size of <em class="parameter"><code>buffer</code></em>
in bytes.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>directory</p></td>
<td class="parameter_description"><p>name of directory to check for localized variant of.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="xfce-get-dir-localized-r.returns"></a><h4>Returns</h4>
<p> pointer to <em class="parameter"><code>buffer</code></em>
or <code class="literal">NULL</code> on error.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-get-path-localized"></a><h3>xfce_get_path_localized ()</h3>
<pre class="programlisting"><span class="returnvalue">gchar</span> *
xfce_get_path_localized (<em class="parameter"><code><span class="type">gchar</span> *dst</code></em>,
                         <em class="parameter"><code><span class="type">gsize</span> size</code></em>,
                         <em class="parameter"><code>const <span class="type">gchar</span> *paths</code></em>,
                         <em class="parameter"><code>const <span class="type">gchar</span> *filename</code></em>,
                         <em class="parameter"><code><span class="type">GFileTest</span> test</code></em>);</pre>
<p><em class="parameter"><code>paths</code></em>
 is a ':'-separated list of pathnames, with:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="literal">%F</code>: the <em class="parameter"><code>filename</code></em>
</p></li>
<li class="listitem"><p><code class="literal">%L</code>: the language string, as returned by <code class="literal">setlocale(LC_MESSAGES, NULL)</code></p></li>
<li class="listitem"><p><code class="literal">%l</code>: the language component of the language string</p></li>
<li class="listitem"><p><code class="literal">%N</code>: application name</p></li>
</ul></div>
<p>Example paths: <code class="literal">/usr/local/lib/%L/%F:/usr/local/share/%N/%l/%F</code></p>
<div class="refsect3">
<a name="xfce-get-path-localized.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>dst</p></td>
<td class="parameter_description"><p>destination buffer.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description"><p>size of <em class="parameter"><code>dst</code></em>
in bytes.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>paths</p></td>
<td class="parameter_description"><p>the path</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description"><p>the filename</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>test</p></td>
<td class="parameter_description"><p>test</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="xfce-locale-match"></a><h3>xfce_locale_match ()</h3>
<pre class="programlisting"><span class="returnvalue">guint</span>
xfce_locale_match (<em class="parameter"><code>const <span class="type">gchar</span> *locale1</code></em>,
                   <em class="parameter"><code>const <span class="type">gchar</span> *locale2</code></em>);</pre>
<p>The locale is of the general form LANG_COUNTRY.ENCODING @ MODIFIER, where
each of COUNTRY, ENCODING and MODIFIER can be absent.</p>
<p>The match is done by actually removing the rightmost element one by one. This
is not entirely according to the freedesktop.org specification, but much easier.
Will probably be fixed in the future.</p>
<div class="refsect3">
<a name="xfce-locale-match.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>locale1</p></td>
<td class="parameter_description"><p>the current locale value as returned by setlocale(LC_MESSAGES,<code class="literal">NULL</code>).</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>locale2</p></td>
<td class="parameter_description"><p>the locale value to match against.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="xfce-locale-match.returns"></a><h4>Returns</h4>
<p> an integer value indicating the level of matching, where
the constant <a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-FULL-MATCH:CAPS" title="XFCE_LOCALE_FULL_MATCH"><span class="type">XFCE_LOCALE_FULL_MATCH</span></a> indicates a full match
and <a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-NO-MATCH:CAPS" title="XFCE_LOCALE_NO_MATCH"><span class="type">XFCE_LOCALE_NO_MATCH</span></a> means no match. Every other value
indicates a partial match, the higher the value, the better
the match. You should not rely on any specific value besides
the constants <a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-FULL-MATCH:CAPS" title="XFCE_LOCALE_FULL_MATCH"><span class="type">XFCE_LOCALE_FULL_MATCH</span></a> and <a class="link" href="libxfce4util-Internationalisation.html#XFCE-LOCALE-NO-MATCH:CAPS" title="XFCE_LOCALE_NO_MATCH"><span class="type">XFCE_LOCALE_NO_MATCH</span></a>,
since the range of returned values may change in the future.</p>
</div>
<p class="since">Since: <a class="link" href="api-index-4-2.html#api-index-4.2">4.2</a></p>
</div>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="XFCE-LOCALE-FULL-MATCH:CAPS"></a><h3>XFCE_LOCALE_FULL_MATCH</h3>
<pre class="programlisting">#define XFCE_LOCALE_FULL_MATCH 50
</pre>
</div>
<hr>
<div class="refsect2">
<a name="XFCE-LOCALE-NO-MATCH:CAPS"></a><h3>XFCE_LOCALE_NO_MATCH</h3>
<pre class="programlisting">#define XFCE_LOCALE_NO_MATCH    0
</pre>
</div>
</div>
<div class="refsect1">
<a name="libxfce4util-Internationalisation.see-also"></a><h2>See Also</h2>
<p>https://developer.gnome.org/glib/stable/glib-I18N.html</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>